---
description: Компонент для поля выбора диапазона дат,
  позволяет пользователю выбрать начальную и конечную дату как через ручной ввод, так и через календарь.
---

<Overview group="dates">

# DateRangeInput [tag:component]

Компонент для поля выбора диапазона дат, позволяет пользователю выбрать начальную и конечную дату как через ручной ввод,
так и через календарь.

</Overview>

<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <DateRangeInput />
  ```
</Playground>

## Применение компонента

> Данный компонент предназначен для использования на планшетах и десктопах.
> При использовании на мобильных устройствах работа компонента не гарантируется.

Данный компонент представляет собой поле формы с возможностью вызова календаря.

Если вам нужен отдельный компонент календаря для выбора диапазона дат, то используйте [`CalendarRange`](/components/calendar-range).

Если вам нужно поле ввода одиночной даты и времени (со всплывающим календарём), то используйте [`DateInput`](/components/date-input).

## Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

Для использования неконтролируемого режима достаточно просто _не_ передавать `value` или передавать `defaultValue`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `value`/`onChange` для задания значения и его изменения.

```jsx
// Неконтролируемое состояние
<DateRangeInput defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]} />;

// Контролируемое состояние
const [date, setDate] = React.useState([new Date(2024, 2, 1), new Date(2024, 2, 10)]);

<DateRangeInput value={date} onChange={setDate} />;
```

## Состояния

### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <DateRangeInput
    defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    disabled
  />
  ```
</Playground>

## Валидация

Свойство `status` используется для визуализации валидации компонента - некорректности заполненного поля (значение `"error"`)
или успешной валидации (значение `"valid"`).

> Если вы используете `DateRangeInput` вместе с [`FormItem`](/components/form-item), вам достаточно указать свойство `status` только у
> [`FormItem`](/components/form-item).

<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <Flex direction="column" gap="m">
    <DateRangeInput
      status="error"
      defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    />
    <DateRangeInput
      status="valid"
      defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    />
  </Flex>
  ```
</Playground>

## Тестирование (e2e) [#e2e]

Для тестирования компонента можно использовать следующие свойство определяющие `data-testid` атрибуты:

- `calendarTestsProps`
- `startDateTestsProps`
- `endDateTestsProps`
- `showCalendarButtonTestId`
- `clearButtonTestId`

Подробности смотри в [Свойства и методы](#api).

## Доступность (a11y) [#a11y]

Компонент обеспечивает базовую доступность, но по умолчанию компонент всё ещё сложно использовать пользователям ассистивных
технологий. Мы доработали компонент так, чтобы сделать его доступным, но это потребовало ломающих изменений в визуальном поведении
компонента.

Новое, доступное поведение можно включить с помощью нового свойства `accessible`.

С `v8` этой свойство включено по умолчанию. Рекомендуется не отключать это поведение, так как этот флаг будет выключен в `v9`

Вот список изменений которые отличают поведение со свойством `accessible` от поведения без:

- иконка календаря видна постоянно (раньше она была видна, только если в `DateRangeInput` нет значения);
- календарь открывается только по клику по иконке календаря, по клику на поле ввода и нажатию клавиши `<Space>`,
  если `DateRangeInput` в фокусе (раньше он открывался сразу при фокусе на `DateRangeInput`);
- при открытии календарь получает фокус. При закрытии календаря фокус возвращается на `DateRangeInput`. Если нужно
  отключить это поведение, используйте свойство `disableFocusTrap`. Если нужно больше контроля над тем, куда возвращать фокус,
  используйте свойство `restoreFocus`.

Из-за особенности реализации `DateRangeInput`, если вкладывать его внутрь `label`, или связывать `label` и `DateRangeInput` через `htmlFor`,
то по клику на `label` фокус будет попадать на `DateRangeInput`, но текст `label` скринридером зачитываться в момент фокуса не будет.
Рекомендуем дублировать текст `label` в `DateRangeInput`, передавая в `DateRangeInput` текст через свойство `aria-label`.

```jsx
<label>
  Период проживания
  <DateRangeInput aria-label="Период проживания" />
</label>
```

```jsx
<label htmlFor="date">Срок действия договора</label>
<DateRangeInput
  id="date"
  aria-label="Срок действия договора"
/>
```

```jsx
<FormItem top="Период бронирования" htmlFor="date">
  <DateRangeInput id="date" aria-label="Период бронирования" />
</FormItem>
```

## Интернационализация (i18n) [#i18n]

> Название месяцев и дней недели определяется исходя из значения `locale` в [`ConfigProvider`](/components/config-provider).

Формат дат и их перевод задаётся с помощью средств браузера [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
Тем не менее компонент, в том числе и календарь, имеют большое количество внутренних интерактивных элементов, которые должны иметь
описание. Особенно важно для доступности (a11y), так как большинство подписей зрячему пользователю не видны, но критически важны
пользователям скринридеров.

Ниже приведён список свойств, которые стоит использовать, если требуется перевести компонент на другой язык. Полный список ищите
в таблице свойств компонента ниже.

- `changeDayLabel`;
- `changeMonthLabel`;
- `changeYearLabel`;
- `changeStartDayLabel`;
- `changeStartMonthLabel`;
- `changeStartYearLabel`;
- `changeEndDayLabel`;
- `changeEndMonthLabel`;
- `changeEndYearLabel`;
- `prevMonthLabel`;
- `nextMonthLabel`;
- `clearFieldLabel`;
- `showCalendarLabel`;
- `calendarLabel`.

## Свойства и методы [#api]

<PropsTable name="DateRangeInput" />
